home *** CD-ROM | disk | FTP | other *** search
/ Aminet 41 / Aminet 41 (2001)(Schatztruhe)[!][Feb 2001].iso / Aminet / util / cli / SED.lha / SED / SED.doc < prev    next >
Text File  |  2000-12-09  |  19KB  |  468 lines
  1. Amiga SED    An Amiga Stream Editor © THOR-Software (Thomas Richter)
  2. ______________________________________________________________________________
  3.  
  4. Purpose of this program:
  5.  
  6.     SED takes an input file, checks each line of this file against a
  7.     pattern supplied on the command line, and generates a new line from
  8.     this pattern match in the destination. This could either mean that
  9.     the matching line is removed completely from the output, replaced
  10.     by a different line, or changed according to the specifications of
  11.     SED.
  12.     
  13.     SED is an approximation of the Unix "stream editor" sed. It is not
  14.     quite as powerful as sed because its command set is currently very
  15.     limited, and it does not support command files. Its pattern syntax
  16.     is different, too. It still looks like "line noise" to me - I didn't
  17.     want to break with this tradition - but it's at least the Amiga kind
  18.     of line noise.
  19.  
  20.     Its pattern matching rules are a superset of the AmigaOs patterns,
  21.     with some additional features like "captured expressions" and more
  22.     powerful "character classes" and "escaping".
  23.  
  24.     SED is useful for automatic processing of text files, e.g. the modi-
  25.     fication of the startup-sequence. SED can also be run as a "filter"
  26.     in which case it reads its input from stdin and prints output to
  27.     stdout. Combine this feature with pipes and you get a very powerful
  28.     text processing tool.
  29.  
  30.     A warning: Pattern matching looks simple, but is full of hard to gasp
  31.     traps. This tool is therefore thought to be for "expert usage". In 
  32.     case you think SED doesn't process your pattern correctly, think
  33.     twice!
  34.  
  35. ______________________________________________________________________________
  36.  
  37. SYNOPSIS:
  38.  
  39. SED    FROM,TO,MATCH/A,REPLACE,CHANGE,DELETE/S,USECASE/S,ALL/S,VERBOSE/S
  40.  
  41. FROM        An (AmigaOs) pattern specifying the input file(s) to process.
  42.         If not given, SED reads from the standard input.
  43.  
  44. TO        The output file where to write the processed lines to. If not
  45.         given, SED writes to the standard output.
  46.  
  47. MATCH        A pattern specification used for filtering the input lines.
  48.         More on the pattern rules below.
  49.         
  50.  
  51. The next options specify what to do with the lines matching the pattern:
  52.  
  53.  
  54. REPLACE        Replace matching lines in the input by this replace rule, do
  55.         not write non-matching lines to the output. The replacement
  56.         rules are given below.
  57.  
  58. CHANGE        Replace matching lines by the replace rule given by this ex-
  59.         presson. In contrast to REPLACE, non-matching lines are placed
  60.         in the destination without change. Useful for modifying a file
  61.         according to a pattern rule.
  62.  
  63. DELETE        Print all lines except those matching the pattern. This
  64.         effectively removes the matching lines from the input file.
  65.  
  66. USECASE        Be case-sensitive. By default, SED is case-insensitive.
  67.         Note that SED differs in this detail from the Un*x sed.
  68.  
  69. ALL        In case the FROM pattern is a wildcard, enter sub-directories
  70.         recursively.
  71.  
  72. VERBOSE        Print information about the file currently scanned, and upon
  73.         entering a directory. Prints also file name and line number
  74.         information for found matches. By default, SED is quiet.
  75.         Note that "Search" is by default not quiet.
  76. ______________________________________________________________________________
  77.  
  78. Pattern specification:
  79.  
  80.     In the following, the syntax of the patterns is specified. By good
  81.     tradition, this is in-comprehensively.
  82.  
  83.     I present first a "quick and dirty" presentation of the available
  84.     patterns as a quick reference which might give you an impression about
  85.     the possibilities. It is all but sufficient to work with SED. Then, a
  86.     detailed and more precise, but also more confusing presentation
  87.     follows.
  88.  
  89. ______________________________________________________________________________
  90.  
  91. Quick guide to patterns:
  92.  
  93. SED patterns work much like Amiga patterns. Unlike in "Search", a pattern is
  94. applied to a FULL line, and not to sub-strings of this line. Which means that
  95. the pattern "hello" matches ONLY the line containing the single word "hello",
  96. nothing more. If you want to match lines containing "hello", use "#?hello#?"
  97. instead - see below for what "#?" means. Unlike Un*x sed, there are no special
  98. characters to match the start or the end of a line. They are not required in
  99. the SED approach.
  100.  
  101. Standard patterns:
  102.  
  103. ?        Matches a single arbitrary character. 
  104. #        Matches zero or more repetitions of the following symbol in
  105.         the AmigaOs sense. Note that # may match zero(!) characters
  106.         as well.
  107.         Therefore, #? matches an arbitrary sequence of at least zero
  108.         characters, hence any string.
  109. +        Matches one or more repetitions of the following symbol
  110.         New to AmigaOs, standard Un*x regular expression.
  111. *        Matches zero or more arbitrary characters in the sense of
  112.         MS-DOS. Note that this is a functional difference to Un*x
  113.         regular expressions where * has the meaning of #.
  114.  
  115.         Note that you need to write ** instead of * if you enclose
  116.         the pattern in double quotes on the shell command line. This
  117.         is because * is also the BCPL escape character. Messy.
  118.  
  119. (...)        Groups the characters in the bracket to a single symbol.
  120.         As for example, #(ab) would match an arbitrary repetition
  121.         of "ab", as the empty string, "ab", "abab" or "ababab", but
  122.         not "aba". 
  123.         Brackets can be nested.
  124.  
  125. (..|..)        The vertical bar means "or". Matches either the left or the
  126.         right string. The bar is only valid within brackets.
  127.  
  128. {...}        Groups expressions much like (...) but captures the contents
  129.         of the sub string that matched the brackets. This captured
  130.         expression is then available for the ouput replacement rules,
  131.         see below for more information. For example,
  132.  
  133.         SED MATCH {#?}.c REPLACE {1}.o
  134.  
  135.         would match all lines ending on ".c", and would capture the
  136.         string in front of the ".c". The "{1}" in the replace pattern
  137.         would insert this string, and would append an ".o". 
  138.         Namely, the above replaces all lines ending on ".c" by a 
  139.         similar line ending by ".o".
  140.         Works very much line the Un*x \(..\) matching.
  141.  
  142. {..|..}        The vertical bar works right the same way here as described
  143.         above. Matches either the left or the right expression, and
  144.         captures the expression that fits.
  145.  
  146. %        Matches the empty string. Useful for patterns like 
  147.         "#?(.c|.o|%)" which could be used to match the source, the
  148.         object code and the final executable of a C project, for
  149.         example.
  150.  
  151. ~        Means "not" and matches all symbols that do not match the
  152.         following symbol. Be warned, ~ is full of traps, see below
  153.         for the full description.
  154.  
  155. [..]        Character classes. Matches a single character on a range of
  156.         valid characters specified in the interior of the bracket.
  157.         For example, "[ac]" would match the single character "a" or
  158.         "c". 
  159.  
  160. [..|..]        Matches either the left or the right character range. Hence,
  161.         [a|c] is equivalent to [ac].
  162.  
  163. [..,..]        Another equivalent formulation of the above. [a,c] is the same
  164.         as [ac] or [a|c].
  165.  
  166. [..-..]        Matches a character range. [a-z] matches all letters - except
  167.         language specific "Umlaute", though, which have different en-
  168.         codings. Several ranges can be grouped much the same way as
  169.         single characters. [a-z|0-9] means "any character or any digit"
  170.         but nothing else.
  171.  
  172. [-..]        Matches all characters up to the specified character. Hence,
  173.         [-z] means "all characters up to z". Note that unlike in Un*x
  174.         implementations, there are no messy rules concering the "["
  175.         itself as character. The escape character "\" must be used to
  176.         specify "[" or "]" itself, see below. 
  177.         This syntax can be combined freely with "|" or "," to specify
  178.         more than one range.
  179.  
  180. [..-]        Matches all characters starting at the given ASCII value. Can 
  181.         be combined freely with "," and "|". There are no messy rules
  182.         concerning "-" in the middle or the end of a character range,
  183.         proper escaping must be used if "]" should be matched.
  184.         [a-] matches therefore all characters "a" and up.
  185.  
  186. [~..]        Matches all characters not in the following range. ~ is applied
  187.         up to the next "|" or ",", unlike in the standard AmigaOs (Arp)
  188.         expression matching. Therefore,
  189.         [~ab] matches all characters except "a" and "b" and is
  190.         equivalent to [~a,~b] and [~a|~b].
  191.  
  192. \        Escape character. Specifies a character to be matched:
  193.  
  194.         \t    Tabulator        \v    Vertical TAB
  195.         \b    Backspace        \r    CR
  196.         \f    Form Feed        \a    Bell
  197.         \n    is INVALID since the end of the line is matched
  198.             by the end of the pattern itself.
  199.         \x..    The character encoded by the hex value following
  200.             the "x". In case this specification is ambigious,
  201.             the number might be terminated by a dot ".". 
  202.             Hence, "\x9.0" matches a tabulator sign and the
  203.             digit "0", whereas "\x90" matches the ASCII char-
  204.             acter of the code hex 90.
  205.             Note that this rule differs from the ANSI-C rule.
  206.         \0..    The character of the ASCII code encoded as an
  207.             octal number.
  208.             The dot is used as above as separator, unlike in
  209.             ANSI-C.
  210.         \$..    Identical to \x.., matches the digit encoded by
  211.             the ASCII code in hex.
  212.         \d    Matches the dollar sign since \$ has a different
  213.             meaning already.
  214.         \#..    Matches the character encoded by the ASCII code
  215.             in decimal notation.
  216.         \h    Matches the hash-mark since \# has a different
  217.             meaning already.
  218.         
  219.         Everything else: The character following the backslash
  220.         itself. Especially, \\ is the backslash itself and \" is
  221.         the double quote.
  222.  
  223.         Note that you must use the backslash to match characters
  224.         which are otherwise part of the pattern syntax, as for
  225.         example "\(" to match the bracket. Note that "#" and "$"
  226.         are special in this sense since "\$" and "\#" are used
  227.         to specify characters by ASCII code.
  228.  
  229. !,",§,$,&,=
  230. -,^,',`,<,>    are reserved for future use AND MUST NOT be used at all.
  231.         Escape them if you need them. However, the dot (".") is
  232.         free, unlike Un*x regexp, same goes for "@" and "/".
  233.  
  234. ..        Everything else: Matches the character itself. Hence "a"
  235.         matches a single "a" much like "[a]".
  236.  
  237. ______________________________________________________________________________
  238.  
  239. Replacement rules:
  240.  
  241. The arguments of REPLACE and CHANGE specify what do with the lines which
  242. matched the specified pattern. Unlike the pattern specification, only the
  243. special operators \ and {..} are allowed. All other operators from the
  244. above list are forbidden and generate an error.
  245.  
  246. \        Escape character, works identically to the \ in the pattern
  247.         and places the single character encoded by the sequence
  248.         following the backslash on the output directly.
  249.  
  250. {..}        Specifies a captured expression to be inserted into the
  251.         output stream. The brackets take up to three arguments:
  252.         The couting number of the regular expression, and optionally
  253.         two arguments how to format the regular expression separated
  254.         by a dot ".". These numbers work very much the same way like
  255.         the arguments to the %s format specifier in ANSI-C.
  256.         
  257.         The first number in the bracket describes which captured
  258.         expression to insert. If it is a positive number, the number
  259.         is simply the index of the captured expression, counting from
  260.         one upwards. 
  261.  
  262.         Each opening bracket "{" in the input pattern starts a new 
  263.         captured expression, hence in nested expressions the other-
  264.         most bracket has the lowest index.
  265.  
  266.         If this number is negative, it counts the captured ex-
  267.         pressions downwards from the last expression.
  268.  
  269.         If the specified expression does not exist, the brackets
  270.         expand into an empty string that is formatted according to
  271.         the rules given by the next three arguments.
  272.  
  273.         {1}    is the first captured expression,
  274.         {3}    is the third expression,
  275.         {-1}    is the last expression,
  276.         {-2}    is the second to last expression.
  277.  
  278.  
  279.         The next number is the field with to print the captured ex-
  280.         pression in. At least the specified number of characters are
  281.         printed, or more if the expression is longer. If the ex-
  282.         pression is too short, the field is padded with blank spaces.
  283.         The expression is right-justified into this field, unless
  284.         the field width is negative in which case the expression is
  285.         left-justified. The sign of the field width is otherwise
  286.         ignored.
  287.         Defaults to 0, i.e. the field is always as small as possible.
  288.  
  289.         The last number is the size limit of the expression. The
  290.         expression will be cut down if it is longer than the specified
  291.         limit. SED will cut the end of the string if this argument is
  292.         positive, or the start of the string if it is negative. The
  293.         sign of the limit is otherwise ignored.
  294.         If the limit is 0, which is the default, the expression will
  295.         not be cut down at all.
  296.  
  297.         {1.10}    is the first captured expression right justified in
  298.             a field of ten characters or longer.
  299.  
  300.         {2.-5.7}is the second captured expression, left justified in
  301.             a field of five characters. At most seven characters
  302.             of the expression will be printed.
  303.  
  304. ..        Everything else: The character itself is printed on the ouput.
  305.  
  306. ______________________________________________________________________________
  307.  
  308. Detailed pattern matching rules:
  309.  
  310. And now for the detailed rules to confuse you completely:
  311.  
  312. - A SYMBOL is either a single character, one of the following operators 
  313. followed by its arguments, a character class [..] or a (..) or {..} sequence.
  314.  
  315. - A PATTERN is a sequence of SYMBOLs.
  316.  
  317. - The POSTFIX of a symbol in a pattern is the subsequence of the pattern
  318. following the symbol, not including the argument of the symbol itself. 
  319. A POSTFIX is always a PATTERN itself.
  320.  
  321. ?        Matches a single character except the end of a string.
  322.  
  323. #        Matches as many repetitions of the following SYMBOL, but
  324.         at least zero such that the POSTFIX of the symbol matches 
  325.         the remaining input.
  326.         Hence, "#" is greedy. There is currently no non-greedy form.
  327.  
  328. +        Matches as many repetitions of the following SYMBOL but
  329.         at least one such that the POSTFIX of the SYMBOL matches the
  330.         remaining input. "+" is greedy.
  331.  
  332. *        is fully equivalent to "#?" and therefore greedy.
  333.  
  334. (...)        groups the PATTERN up to the next | or ) into a SYMBOL
  335.         which matches if the contents of the brackets match.
  336.  
  337. (..|..)        An or-combined SYMBOL matches if one of the PATTERNS
  338.         in the bracket match such that the POSTFIX matches the 
  339.         remaining input.
  340.  
  341. {...},{..|..}    Similar to the above except that the matched string is
  342.         captured.
  343.  
  344. %        Is completely ignored as pattern and gobbles no character
  345.         from the input sequence at all. 
  346.  
  347. ~        Matches the longest subsequence or at least zero characters
  348.         that does not match the following SYMBOL such that the 
  349.         POSTFIX of the SYMBOL still matches the remaining input. 
  350.         "~" is greedy and will try to match as many characters first.
  351.  
  352.         Note that a SYMBOL could either be a single character or a
  353.         sequence of characters grouped by () or #. Since a single
  354.         character cannot match a string larger or smaller than one
  355.         character, ~ followed by a one-character symbol will match
  356.         all subsequences except those whose postfix either don't
  357.         match the postfix of the character, or which match the
  358.         character and the postfix.
  359.  
  360.         This is *very* tricky and you should think about the con-
  361.         sequences of this rule twice. More examples below.
  362.  
  363. [..]        Character classes. Groups a range of characters into a
  364.         SYMBOL that matches exactly a single character, but never
  365.         the empty string.
  366.  
  367.         ~ in character classes is special: If there is a not-sequence
  368.         in a character class, it matches if all not-sequence match at
  369.         once and one or more of the ordinary sequences match. Hence
  370.  
  371.         [~p,~q,a-z]
  372.  
  373.         matches all letters except p and q.
  374.  
  375. ..        Everything else matches exactly the the one character that
  376.         it represents. They will not match the empty string.
  377.  
  378. ______________________________________________________________________________
  379.  
  380. Some examples of patterns to think of:
  381.  
  382. %        Matches only empty lines in the input.
  383.  
  384. ~%        Matches only non-empty lines in the input.
  385.  
  386. #?.c        Matches all lines ending on ".c"
  387.  
  388. The#?        Matches all lines starting with "The".
  389.  
  390. #?Example#?    Matches all lines containing the word "Example".
  391.  
  392. Example#?    Matches all lines starting with the word "Example".
  393.  
  394. Example        Matches all lines consisting of the single word "Example".
  395.  
  396. #?        Matches all lines.
  397.  
  398. #?(.c|.o|%)    Matches all lines (think about why!).
  399.  
  400. foo(.c|.o|%)    Matches all lines consisting entirely of the word "foo", "foo.c"
  401.         or "foo.o".
  402.  
  403. foo(.c|.o|)    Just the same.
  404.  
  405. ~(Example)    Matches all lines except the line consisting of the single word
  406.         "Example".
  407.  
  408. ~(#?Example#?)    Matches all lines that do not contain the word "Example".
  409.  
  410. ~(ab)cd        Matches all lines that do not start with "ab" and that end on 
  411.         "cd". Especially, this would match "bccd". It would also match
  412.         the line "cd" since "ab" does not match the empty sequence in
  413.         front of "cd". (think about this!)
  414.  
  415. ~#a.c        Matches all lines ending by ".c" except those where the ".c" is
  416.         prefixed by an arbitrary number of a's, including zero a's.
  417.         Hence, it would match "bc.c" and even "ab.c", but not "a.c" or
  418.         ".c" as the last consists of zero a's and one ".c". It would
  419.         not match "bc.o". This is identically to ~(#a).c since # binds
  420.         the following a.
  421.  
  422. ~(#ab)#?    Matches all lines except those starting with a possibly empty
  423.         sequence of a's followed by a single b. Hence, does not match
  424.         aaabccc or bccc.
  425.  
  426. ~(#[ ,\t];)#?    Matches all lines except those starting with a possibly empty
  427.         sequence of blanks or tabulators followed by a colon. Hence,
  428.         for a shell script, this would match all non-comment lines.
  429.  
  430. ~(#[ ,\t];)if#?    This is a tricky one. Unlike what you might think, this does
  431.         not match all non-comment lines starting with if. It also
  432.         matches lines starting with a semicolon provided the string
  433.         "if" is in the line and not directly behind the semicolon.
  434.         Note that this is the intended behaivour. For example, it
  435.         would match 
  436.  
  437.         ;aifb
  438.  
  439.         The reason is simple: This is a string ";a" that does not
  440.         match the symbol #[ ,\t]; followed by "ifb" which matches
  441.         if#?.
  442.  
  443.         What you want here instead is #[ ,\t]if#? which matches
  444.         all if-lines with additional, at least zero, blanks or tabs 
  445.         in front.
  446.  
  447.         The above example shows again the tricky nature of pattern
  448.         matching.
  449.  
  450. A real life example would be
  451.  
  452. sed from S:Startup-Sequence match "{#[ ,\t]}RunBack{#?}" change "{1}Launch{2}"
  453.  
  454. which would replace all invocations of "RunBack" in the Startup-Sequence by
  455. similar invocations of "Launch".
  456.  
  457. Another example to think about as exercise:
  458.  
  459. ({}|{#[~;]+[ \t]}#[~; \t][/:]|{}#[~; \t][/:]|{#[~;]+[ \t]})FooBar{|[ \t;]#?}
  460.  
  461. Yes, this pattern is useful. Consider again S:Startup-Sequence as input file
  462. and think about what this could possibly do. Note that some expressions are
  463. captured. (Hey, I said this would look like line noise!)
  464. ______________________________________________________________________________
  465.  
  466. Thomas Richter,
  467.         December 2000
  468.